Reinstate supplemental API remarks (System.Runtime)#12699
Merged
Conversation
gewarren
requested review from
a team,
AaronRobinsonMSFT,
StephenMolloy and
jkoritzinsky
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
This PR reinstates “supplemental API remarks” directly into this repo’s ECMA XML files for several System.Runtime-related APIs (per #12613), replacing the previous pattern of linking out to conceptual documentation. It also adds/relocates snippet assets to support the restored remarks.
Changes:
- Replaces “Supplemental API remarks…” external links with inlined markdown remarks in multiple
xml/type docs. - Updates
InternalsVisibleToAttributedocs to point at new snippet paths and adds new snippet projects/files. - Adds new snippet project files (C#/VB) to support compilation/validation of the referenced code samples.
Reviewed changes
Copilot reviewed 34 out of 38 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| xml/System.Runtime.Versioning/ComponentGuaranteesAttribute.xml | Inlines previously external supplemental remarks and references snippet files. |
| xml/System.Runtime.Serialization/XsdDataContractExporter.xml | Inlines supplemental remarks content for the exporter. |
| xml/System.Runtime.Serialization/IExtensibleDataObject.xml | Inlines supplemental remarks content for version-tolerant serialization. |
| xml/System.Runtime.Serialization/DataContractSerializer.xml | Inlines supplemental remarks content (includes a .NET Framework partial-trust section that needs adjustment). |
| xml/System.Runtime.Serialization/DataContractAttribute.xml | Inlines supplemental remarks content and guidance for data contracts. |
| xml/System.Runtime.Loader/AssemblyLoadContext.xml | Inlines supplemental remarks content for load contexts. |
| xml/System.Runtime.InteropServices/SafeHandle.xml | Inlines supplemental remarks content for SafeHandle usage and motivation. |
| xml/System.Runtime.InteropServices/ICustomMarshaler.xml | Inlines supplemental remarks content and adds snippet references (includes .NET Framework wording to neutralize). |
| xml/System.Runtime.InteropServices/ComWrappers.xml | Inlines supplemental remarks content describing ComWrappers concepts. |
| xml/System.Runtime.InteropServices/COMException.xml | Inlines supplemental remarks content for COMException handling guidance. |
| xml/System.Runtime.CompilerServices/RuntimeHelpers.xml | Inlines supplemental remarks for RuntimeHelpers.GetHashCode and adds snippet references. |
| xml/System.Runtime.CompilerServices/InternalsVisibleToAttribute.xml | Inlines supplemental remarks and repoints snippet references; includes a minor punctuation fix needed. |
| snippets/visualbasic/System.Runtime.Versioning/ComponentGuaranteesAttribute/Overview/Project.vbproj | Adds a VB snippet project for ComponentGuaranteesAttribute examples. |
| snippets/visualbasic/System.Runtime.Versioning/ComponentGuaranteesAttribute/Overview/apply1.vb | Adds VB snippet source for the ComponentGuaranteesAttribute examples. |
| snippets/visualbasic/System.Runtime.InteropServices/ICustomMarshaler/Overview/source.vb | Adds VB snippet source for ICustomMarshaler remarks. |
| snippets/visualbasic/System.Runtime.InteropServices/ICustomMarshaler/Overview/Project.vbproj | Adds a VB snippet project for ICustomMarshaler examples. |
| snippets/visualbasic/System.Runtime.CompilerServices/RuntimeHelpers/GetHashCode/Project.vbproj | Adds a VB snippet project for RuntimeHelpers.GetHashCode examples. |
| snippets/visualbasic/System.Runtime.CompilerServices/RuntimeHelpers/GetHashCode/gethashcodeex1.vb | Adds VB snippet source for RuntimeHelpers.GetHashCode examples. |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/UtilityLib/utilitylib.vb | Adds VB UtilityLib snippet source (missing a corresponding Project.vbproj). |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/friend2.vb | Removes the old VB Friend2 snippet location (relocated under Overview/Friend/). |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/multiple2.vb | Adds VB snippet showing multiple friend assemblies via one assembly block. |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/multiple1.vb | Adds VB snippet showing multiple friend assemblies via multiple attributes. |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/Friend2.vbproj | Adds a VB snippet project for friend-assembly examples. |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/friend2.vb | Adds relocated VB Friend2 snippet (currently has the key call commented out). |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/friend1.vb | Updates/relocates VB Friend1 snippet content. |
| snippets/visualbasic/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/assembly1.vb | Adds relocated VB Assembly1 snippet content for signed-assembly example. |
| snippets/csharp/System.Runtime.InteropServices/ICustomMarshaler/Overview/source.cs | Adds C# snippet source referenced by the restored ICustomMarshaler remarks. |
| snippets/csharp/System.Runtime.InteropServices/ICustomMarshaler/Overview/Project.csproj | Adds a C# snippet project for ICustomMarshaler examples. |
| snippets/csharp/System.Runtime.CompilerServices/RuntimeHelpers/GetHashCode/gethashcodeex1.cs | Adds C# snippet source referenced by the restored RuntimeHelpers remarks. |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/UtilityLib/UtilityLib.csproj | Adds a C# UtilityLib snippet project for InternalsVisibleTo examples. |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/UtilityLib/utilitylib.cs | Adds C# UtilityLib snippet source for InternalsVisibleTo examples. |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/friend2.cs | Removes the old C# Friend2 snippet location (relocated under Overview/Friend/). |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/multiple2.cs | Adds C# snippet showing multiple friend assemblies in one attribute list. |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/multiple1.cs | Adds C# snippet showing multiple friend assemblies via multiple attributes. |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/Friend2.csproj | Adds a C# snippet project for friend-assembly examples (needs a ProjectReference). |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/friend2.cs | Adds relocated C# Friend2 snippet (needs compile + example correctness fixes). |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/friend1.cs | Updates/relocates C# Friend1 snippet content (had a compile break due to renaming). |
| snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/assembly1.cs | Adds relocated C# Assembly1 snippet content for signed-assembly example. |
Comments suppressed due to low confidence (1)
snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/Friend/friend1.cs:29
- The snippet renames the helper type to
FileUtilities1, butMainstill callsFileUtilities.AppendDirectorySeparator, which will fail to compile. Update the call site to use the new type name (or keep the original type name consistent across the snippet).
BillWagner
approved these changes
Jun 4, 2026
Member
BillWagner
left a comment
BillWagner
left a comment
There was a problem hiding this comment.
This LGTM @gewarren
I had a couple code suggestions, and then it's ready.
Co-authored-by: Bill Wagner <wiwagn@microsoft.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Contributes to #12613.
Also removes .NET Framework remarks.